home *** CD-ROM | disk | FTP | other *** search
/ Magnum One / Magnum One (Mid-American Digital) (Disc Manufacturing).iso / d18 / pibcat.arc / PIBCAT.DOC < prev    next >
Encoding:
Text File  |  1989-03-31  |  20.5 KB  |  542 lines
  1. Introduction
  2. ============
  3.  
  4. PIBCAT.COM is a disk-cataloguing program.  It lists all files in all
  5. subdirectories on a given disk, and also lists the entries in library files
  6. of the .ARC, .LBR, .LZH, .LZS, .MD, .PAK, .ZOO, and .ZIP formats.  You may
  7. provide a match criterion for files, and you may suppress the library files
  8. content listing.
  9.  
  10. The complete source code for PibCat is also available.  PibCat is written
  11. in Turbo Pascal v5.0.
  12.  
  13.  
  14. System requirements
  15. ===================
  16.  
  17. IBM PC or compatible under MS DOS or PC DOS v2.0 or higher with
  18. at least 128K of RAM.  The more RAM available, the greater the
  19. number of files which can be processed.
  20.  
  21.  
  22. Restrictions on use
  23. ===================
  24.  
  25. I hereby contribute the entire PibCat program and source to the public
  26. domain.  As a result, there are no restrictions on what you can do
  27. with this program or code.  However, as a matter of courtesy, I ask that
  28. you give me credit if you use any part of this code in developing other
  29. software, and I STRONGLY urge you to release the source code for such
  30. projects to the public domain so that all of us can benefit.
  31.  
  32. If you make any nifty changes or enhancements to PibCat itself, PLEASE
  33. upload the changes so all of us can profit by them.
  34.  
  35. Note that System Enhancements Associates (SEA) regards ARC as their trademark.
  36. Should you wish to use the code in PibCat, that reads the directory of
  37. ARC files, in your own program, I suggest you contact SEA for licensing
  38. details and restrictions.  I WILL NOT ACCEPT any responsibility for any
  39. legal problems that may arise as a result of the use or misuse of the ARC
  40. processing code contained in PibCat.  I do not have any agreement myself
  41. with SEA;  SEA has indicated that public domain programs may process
  42. .ARC files without any restrictions.
  43.  
  44.  
  45. Liability
  46. =========
  47.  
  48. PibCat and its related source code is distributed as-is.  I, Philip R. Burns,
  49. the author, disclaim all warranties, expressed or implied.  I will not assume
  50. any liability for damages either from the direct use of this product or as
  51. a consequence of the use of this product.
  52.  
  53.  
  54. Files in Release
  55. ================
  56.  
  57. The following files comprise the complete PibCat v1.7 release:
  58.  
  59.    PIBCAT.DOC      -- The document file which you're reading now
  60.    PIBCAT.EXE      -- The executable version of PibCat
  61.  
  62.    MAKEPCAT.BAT    -- Batch file which recompiles PibCat when executed
  63.    PIBCAT.GLO      -- Global definitions for PibCat
  64.    PIBCAT.PAS      -- Main program for PibCat
  65.    PIBCATA.PAS     -- ARC/PAK processing code
  66.    PIBCATD.PAS     -- DWC processing code
  67.    PIBCATK.PAS     -- ZIP processing code
  68.    PIBCATL.PAS     -- LBR processing code
  69.    PIBCATM.PAS     -- MD processing code
  70.    PIBCATY.PAS     -- LZH/LZS processing code
  71.    PIBCATS1.PAS    -- Subroutines for PibCat, part 1
  72.    PIBCATS2.PAS    -- Subroutines for PibCat, part 2
  73.    PIBCATS3.PAS    -- Subroutines for PibCat, part 3
  74.    PIBCATS4.PAS    -- Subroutines for PibCat, part 4
  75.    PIBCATZ.PAS     -- ZOO processing code
  76.  
  77. PibCat is written in Turbo Pascal v5.0.
  78.  
  79.  
  80. Usage
  81. =====
  82.  
  83. At the DOS prompt, type
  84.  
  85.     PIBCAT <options>
  86.  
  87. where the <options> are as follows:
  88.  
  89.     PIBCAT v /c /e=filespec /f=filespec /i=indent /l /m=margin /n
  90.              /o=filename /p=pagesize /t=timezone /x /2
  91.  
  92.        v               volume (drive letter) to catalog
  93.                        (default is current drive)
  94.                        If given as ?, this text is displayed.
  95.  
  96.        /a              Requests that PibCat output be appended to
  97.                        the file specified by "/o=".  Default is to
  98.                        overwrite the the output file.
  99.  
  100.        /c=format       Produce condensed listing suitable for
  101.                        input to a database manager or sorting program.
  102.                        Two formats are available:  a columnar format
  103.                        specified as "/c=column" or a comma-delimited
  104.                        format specified as "/c=comma".  Specifying
  105.                        "/c" without a format produces the columnar
  106.                        format.  This option overrides all other
  107.                        formatting options.
  108.  
  109.        /e=filespec     DOS file spec to match for entries contained
  110.                        in library files (default is *.* -- list all entries).
  111.                        The match is not case sensitive.
  112.  
  113.        /f=filespec     DOS file spec to match when listing
  114.                        (default is *.* -- list all files)
  115.  
  116.        /i=indent       # columns to space for library file entries
  117.                        (default is 0)
  118.  
  119.        /l              display long file names in .ZOO, .LZH, .LZS, .MD, and
  120.                        .ZIP files, and add subdirectory name for .ARC files
  121.                        (default is to display short file names only)
  122.  
  123.        /m=margin       left margin to leave (default is 0)
  124.  
  125.        /n              expand library file contents after
  126.                        displaying subdirectory contents rather than
  127.                        immediately following the file name
  128.                        (default is to list contents immediately.)
  129.  
  130.        /o=filename     write catalog listing to file "filename"
  131.                        (default is "CATALOG.LIS")
  132.  
  133.        /p=pagesize     paginate listing using "pagesize" lines
  134.                        (default is no pagination)
  135.  
  136.        /s=filename     write status information to file "filename"
  137.                        (default is DOS standard output = display)
  138.  
  139.        /t=timezone     number of hours local time lags/leads Greenwich
  140.                        Mean Time (default is 7 hours)
  141.  
  142.        /x              don't list library file contents
  143.                        (default is to list library file contents)
  144.  
  145.        /2              Opens files without SHARE for DOS v2.x compatibility
  146.                        (default is to open files with share for DOS v3.1
  147.                        and above)
  148.  
  149.  
  150. Aborting
  151. ========
  152.  
  153. Hit <CTRL>Break to abort catalog listing.
  154.  
  155.  
  156. Output
  157. ======
  158.  
  159. For each selected file, the file name, size in bytes, and time
  160. and date of creation are displayed.  The files are displayed in
  161. sorted order by name.  All subdirectories of each directory
  162. are searched and listed automatically.  By default, a non-paginated
  163. listing is written to CATALOG.LIS.  Use "/p=" to get a paginated
  164. listing (each page has a page number and is separated from the
  165. previous page by an Ascii form-feed character  (^L) ).
  166.  
  167. The "/c" parameter requests output consisting of one line for each file
  168. and (optionally) each entry in library files.  This output style is
  169. suitable for use as input to sorting programs and database managers.
  170. Two formats are available:
  171.  
  172.    /c=column:  the items appear in fixed columns as indicated below:
  173.  
  174.          Columns   Contents
  175.          =======   ========
  176.  
  177.           1 - 12   File name
  178.          14 - 22   File size in bytes
  179.          24 - 31   Date in YY/MM/DD format
  180.          33 - 37   Time in 24 hour HH:MM format
  181.          39 - 50   Library Name  (if file is member of a library)
  182.          52 - 63   Volume label
  183.          65 - 130  Path (without trailing file name)
  184.  
  185.    /c=comma:   the items are formatted as above, but a comma appears
  186.                in columns 13, 23, 32, 38, 51, and 64 to separate the items.
  187.  
  188. If a file is a member of a library, then the path is that of the library
  189. file itself, NOT any path stored in the library.
  190.  
  191. The same file name, size, and time/date information is presented
  192. for members of library files like .ARC, .LBR, .LZH, .LZS, .MD, .PAK, .ZIP,
  193. and .ZOO files.  The file names within library files NOT sorted by PibCat.
  194. However, many of these library files are created with names in sorted order
  195. anyway.
  196.  
  197. For .LBR files, the time and date of the last update for each member,
  198. not the original creation time and date, are displayed.  Some .LBR
  199. files do not record creation or update times, and in that case, the
  200. time/date fields are not displayed.
  201.  
  202. For .ZOO files, deleted entries which still exist in the .ZOO file
  203. will be marked as "(deleted)" in the output listing.  Deleted entries
  204. are not included in the totals for files within libraries.  Note that
  205. the file names in .ZOO files are stored in LOWER case; PibCat DOES NOT
  206. map these names to upper case in the listing file.
  207.  
  208. .LZH, .LZS, .MD, .ZIP, and .ZOO files can store long file names as well
  209. as short file names.  By default, the file names displayed are the "short"
  210. names and do not include path names.  To see the complete file name including
  211. path, specify the "/l" option.  The extended name is listed to the right
  212. of the file creation date, and thus may extend past the usual printing
  213. column.  If a .ZOO file entry is marked as deleted, then the long name
  214. for that file will not be displayed.
  215.  
  216. Some programs (PAK16.EXE, for example) produce files with a .ARC-compatible
  217. directory structure.  PibCat therefore will try to process .PAK files as
  218. .ARC files.
  219.  
  220. SEA's ARC600.EXE and later programs allow for storing of the subdirectory
  221. name and also a long file name.  At this time, PibCat will display the
  222. subdirectory names when "/l" is specified, but the PibCat does NOT display
  223. any long file names.
  224.  
  225.  
  226. A Note About Dates in DWC
  227. =========================
  228.  
  229. Dean Cooper's excellent DWC program, which creates .DWC libraries, stores
  230. file creation/modification dates and times in Unix format:  the number of
  231. seconds elapsed from 0:00 GMT (Greenwich Mean Time) on January 1, 1970 to
  232. the creation/modification time of the file.  This was to allow file times
  233. and dates to be adjusted for any time zone.
  234.  
  235. Unfortunately, DWC is compiled with Microsoft C, which has the astonishing
  236. and brain-damaged gall to assume that the local time zone is the U.S.
  237. Pacific time zone (!).  This means that the file dates and times in the
  238. .DWC file are stored as if local time were Pacific time.  Microsoft provides
  239. the TZ= environment variable to set the local time zone correctly.
  240. Unfortunately, many users of DWC do not set the TZ= environment variable
  241. correctly, and DWC does not store the current time zone in the .DWC library
  242. itself.  This makes it nearly impossible to get the file dates and times
  243. correct when moving a .DWC file from one machine to another.
  244.  
  245. PibCat tries to circumvent this problem by subtracting seven or eight hours
  246. from the time stamp of each file as given in the .DWC file.  (The difference
  247. between seven and eight depends upon whether Microsoft thinks daylight savings
  248. time or standard time is in effect.)
  249.  
  250. Alternatively, if you know the hour value specified in the TZ= environment
  251. variable when the .DWC file was created, you can specify that hour value
  252. to PibCat using the  /t=timezone  parameter.  Time zones which lag
  253. GMT are entered as positive numbers; time zones which lead GMT are entered as
  254. negative numbers.  The hour value you specify will be used to adjust the
  255. file times rather than the default of Pacific time.
  256.  
  257. PibCat uses the same assumptions as Microsoft about what days are considered
  258. daylight savings time and standard time:  daylight savings time is in effect
  259. from 3 AM on the first sunday in April, to 1 AM on the last Sunday in October.
  260. Standard time is in effect otherwise.  If you do not want PibCat to adjust
  261. times using these standard time/daylight savings time dates, then append
  262. an 'A' to the number of hours you specify in  /t=.
  263.  
  264. For example, if you know that the /TZ= string originally specified Eastern
  265. time:
  266.  
  267.    SET TZ=est5edt
  268.  
  269. then you can invoke PibCat with the following /t parameter:
  270.  
  271.    PIBCAT /t=5
  272.  
  273. This will adjust dates in .DWC files by five hours for days covered by
  274. standard time; days covered by daylight savings time will be adjusted by
  275. six hours.
  276.  
  277. If you want the adjustment to always be five hours regardless of daylight
  278. savings or standard time, then specify:
  279.  
  280.    PIBCAT /t=5A
  281.  
  282. If you want to know more about the TZ= environment variable, consult the
  283. Microsoft C Run-Time Library Reference manual.
  284.  
  285.  
  286. A Note About Zip Files
  287. ======================
  288.  
  289. PibCat does not handle .ZIP files which span more than one diskette.
  290. Also, PibCat only reports entries based upon the central file directory,
  291. not the scattered directory entries.
  292.  
  293.  
  294. If you get "Cannot open file" messages for library files
  295. ========================================================
  296.  
  297. For DOS 3.1 and above, PibCat opens library files for reading with an
  298. access mode type of 64.  The output file is opened with an access mode
  299. type of 66.  These access modes appear to be good choices for most
  300. networks, SHARE, and so on.  However, they may not work for all systems.
  301. If you receive "Cannot open file xxxx.yyy" for all library files (.ARC,
  302. .ZIP, etc.) then chances are you need to turn off the share compatibility
  303. by specifying the "/2" parameter.
  304.  
  305. For versions of DOS prior to v3.1, or when the "/2" parameter is specified,
  306. PibCat uses a read access mode type of 0 and a write access mode of 2.
  307.  
  308.  
  309. Examples of PibCat Use
  310. ======================
  311.  
  312. To get abbreviated help:
  313.  
  314.    PIBCAT ?
  315.  
  316. To catalog the currently logged disk:
  317.  
  318.    PIBCAT
  319.  
  320. To catalog disk C:
  321.  
  322.    PIBCAT C
  323.  
  324. The output goes to file CATALOG.LIS by default.  To specify an alternate
  325. output file called MYDIR.LIS:
  326.  
  327.    PIBCAT C /O=MYDIR.LIS
  328.  
  329. To select a match criterion:
  330.  
  331.    PIBCAT C /F=*.bat         ==> only list .BAT files
  332.    PIBCAT C /F=\bozo         ==> only list files in C:\bozo\ and its
  333.                                  subdirectories
  334.    PIBCAT /F=*.ZOO /E=*.PAS  ==> List only .ZOO files and any .PAS files
  335.                                  contained in those .ZOO files
  336.    PIBCAT /E=*.C?M           ==> List all files, but only entries like
  337.                                  *.C?M (*.COM, *.CQM, etc.) in library files.
  338.  
  339. To get a paginated listing:
  340.  
  341.    PIBCAT /P=60              ==> Paginated listing assuming 60 lines per page
  342.                                  (Form feeds separate pages)
  343.  
  344. To get the listing indented (perhaps for binding):
  345.  
  346.    PIBCAT /M=10              ==> Indent listing file by 10 columns
  347.  
  348. To indent the library entry listings further than the regular directory
  349. listings:
  350.  
  351.    PIBCAT /I=5               ==> Indent library listings 5 columns further
  352.                                  to the right than regular directory listings
  353.  
  354. To prevent Pibcat from listing the contents of library files:
  355.  
  356.    PIBCAT /X                 ==> No expansion of library files
  357.  
  358. To get library file contents listing after displaying the subdirectory
  359. entries (as in PibCat v1.0):
  360.  
  361.    PIBCAT /N                 ==> List contents of library files after all
  362.                                  file names for a given subdirectory
  363.  
  364. Produce a file catalog suitable for input to a database manager:
  365.  
  366.    PIBCAT /C                 ==> No expansion of library files
  367.  
  368. Turn off share mode:
  369.  
  370.    PIBCAT /2                 ==> Files not opened in share mode.
  371.  
  372. Of course the various parameters can be used together.
  373.  
  374.  
  375. Recompiling the source
  376. ======================
  377.  
  378. Extract all the source files to a working directory, and then execute
  379. the MAKEPCAT.BAT to recompile PibCat.  You will need Turbo Pascal v5.0.
  380.  
  381. The PIBCAT.EXE file as distributed has been compressed with Graeme W. McRae's
  382. SCRNCH program.  The compressed version of PibCat is about half the size
  383. of the uncompressed version.  The compressed PIBCAT.EXE is executed exactly
  384. the same way as the uncompressed version would be;  the uncompression is
  385. automatic and is done "on the fly."
  386.  
  387.  
  388. Acknowledgments
  389. ===============
  390.  
  391. V1.0
  392. ====
  393.  
  394. The archive search code is based in part on TPARCV.PAS by Michael Quinlan
  395. and ARCV.ASM by Vern Buerg.  The library search code is based in part upon
  396. LU.PAS by Steve Freeman.  Bob Blacher was very helpful in testing PibCat.
  397.  
  398. V1.1
  399. ====
  400.  
  401. The idea and code for implementing the '/n'-style expansion of .LBR and
  402. .ARC files was provided by Stephen Falatko.  Thank you Stephen!  I have
  403. altered the .ARC/.LBR contents display so that .ARC/.LBR entries stand out
  404. better when the contents are displayed as part of the main listing.
  405.  
  406. Dave Seidman pointed out that MS DOS 2.x bugs prevented proper display
  407. of volume labels.  He provided a routine to obtain the correct
  408. volume label for DOS 2.x versions.  (Regrettably, the date and time for
  409. labels appears inaccessible using any of the standard functions under
  410. MS DOS 2.x.)  I have altered the volume display code to check for the DOS
  411. version, and use Dave's method for obtaining the volume label under DOS 2.x.
  412. The date and time for the label are NOT printed under DOS 2.x.
  413.  
  414. Several people complained that the /f= match criterion didn't extend to
  415. members of library files.  I've added the /e= match criterion in response.
  416.  
  417. -- Phil Burns
  418.    January 30, 1987
  419.  
  420. V1.2
  421. ====
  422.  
  423. Convert to Turbo v4.0.  No specification changes.  The new version is
  424. an EXE file, i.e., PIBCAT.EXE.
  425.  
  426. -- Phil Burns
  427.    September 1, 1987
  428.  
  429. V1.3
  430. ====
  431.  
  432. Minor code revisions to work better with TP4.  No specification changes.
  433.  
  434. -- Phil Burns
  435.    April 27, 1988
  436.  
  437. V1.4
  438. ====
  439.  
  440. Lewis Paper pointed out a couple of bugs in v1.3:
  441.  
  442.    (1)  Files marked as "read only" could not be read.
  443.  
  444.    (2)  A formatting bug caused by a bad call to DUPL caused
  445.         occasional system crashes.
  446.  
  447. My thanks to Lewis for pointing out the problems.  These bugs are
  448. fixed in v1.4.
  449.  
  450. V1.5
  451. ====
  452.  
  453. Add processing of .DWC, .MD, and .ZOO files.  No specification changes.
  454. Now designed to be compiled with Turbo Pascal v5.0.
  455.  
  456. Previous versions of PibCat limited the total number of files along the
  457. current subdirectory path (not including members of library files) to 2048.
  458. This used to be quite sufficient, since few people had nested subdirectories
  459. such that the total number of files in the nested subdirectories exceeded
  460. 2048.  Nowadays, larger disks and huge numbers of files are more common, so
  461. the 2048 file limit is too small.
  462.  
  463. PibCat v1.5 uses all available memory to hold file descriptor entries.
  464. Each file descriptor takes 22 bytes.  As an example, this means that over
  465. about 20,000 files can exist along a given path of nested directories with
  466. about 500K of available memory.
  467.  
  468. PibCat v1.5 opens files in SHARE mode under DOS 3.0 and above.  This should
  469. reduce conflicts with networks.  The "/2" parameter may be used to force
  470. DOS 2.x compatibility in the choice of file open modes even when DOS v3.1
  471. or above is installed.
  472.  
  473. There are programs (PAK10, for example) which create files with .ARC file
  474. directory structure but with different extensions.  PAK10 uses .PAK, and so
  475. PibCat v1.5 will try to list the contents of a .PAK file as if it were a
  476. .ARC file.
  477.  
  478. I used Graeme W. McRae's SCRNCH program to reduce the size of the PIBCAT.EXE
  479. file by about 40%.  The extra time required to decompress the file when it
  480. begins executing is negligible.
  481.  
  482. -- Phil Burns
  483.    November 7, 1988
  484.  
  485. V1.6
  486. ====
  487.  
  488. PibCat v1.6 lists the contents of .ZIP files.  .ZIP files are created
  489. by the PKWare utilities from Phil Katz.  Note that PibCat only uses
  490. the information from the central file directory, not the scattered file
  491. headers.  Also, PibCat will not process .ZIP files that span more
  492. than a single disk.
  493.  
  494. Thanks to Ken Brown for his ZIPV program (written in "C" ) which
  495. demonstrated how to read the central file directory of .ZIP files.
  496.  
  497. PibCat v1.6 also handles the subdirectory structure headers added to
  498. SEA's ARC program beginning with ARC v6.0.
  499.  
  500. The new "/c" program parameter causes PibCat to output a condensed listing
  501. suitable as input to other programs such as database managers, sorting
  502. programs, etc.
  503.  
  504. I've changed the share access modes to 64 for reading files and 66 for
  505. writing files, which hopefully will work on more systems than the
  506. previous choices.
  507.  
  508. -- Phil Burns
  509.    March 2, 1989
  510.  
  511. V1.6.1
  512. ======
  513.  
  514. Several people reported a rather embarrassing bug in v1.6:  PibCat will
  515. not expand entries in library files on disks other than the current
  516. default disk.  PibCat v1.6.1 fixes that bug.  Sorry folks.
  517.  
  518. -- Phil Burns
  519.    March 15, 1989
  520.  
  521. V1.7
  522. ======
  523.  
  524. V1.7 of PibCat can list the entries in .LZH files created by the LHARC.EXE
  525. program of Haruyasu Yoshizaki, and the .LZS files created by the LARC.EXE
  526. program of K. Miki.  The format of the directory entries in .LZH and .LZS
  527. files is identical.
  528.  
  529. The "/s=" parameter routes the status listing to a file (the DOS standard
  530. output file is the default).
  531.  
  532. The "/c=" parameter now allows for both the fixed-column format introduced
  533. with v1.6 of PibCat and a comma-delimited format new to v1.7.  Some
  534. commonly used database programs are evidently unable to deal with fixed-field
  535. input.  Another example of rampant brain-damage, I guess.
  536.  
  537. The "/a=" parameter requests PibCat to append to the output file rather
  538. than overwriting it.
  539.  
  540. -- Phil Burns
  541.    April 1, 1989
  542.